fast-safe-stringify

What is fast-safe-stringify?

The fast-safe-stringify package is designed for safely converting JavaScript objects into JSON strings without running into issues like circular references, which can cause the native JSON.stringify to throw an error. It aims to provide a fast and safe way to serialize objects, including those that may contain circular references, functions, and other non-JSON-safe values.

What are fast-safe-stringify's main functionalities?

Safe serialization of circular references

This feature allows you to safely serialize objects that contain circular references, which would otherwise throw an error with JSON.stringify.

const stringify = require('fast-safe-stringify');
const obj = {};
obj.a = { b: obj };
console.log(stringify(obj));

Stable serialization

Provides an option for stable serialization, where the output JSON string's property order is deterministic, making it suitable for hashing, comparisons, etc.

const stringify = require('fast-safe-stringify').stable;
const obj = { c: 8, b: [{z:6,y:5,x:4},7], a: 3 };
console.log(stringify(obj));

Serialization with decycler

Allows custom handling of circular references during serialization, enabling you to replace or transform circular references in the resulting JSON string.

const stringify = require('fast-safe-stringify').stable;
function replaceCircular(key, value, circular) { return circular ? '[Circular]' : value; }
const obj = {};
obj.a = obj;
console.log(stringify(obj, replaceCircular));

Other packages similar to fast-safe-stringify

json-stringify-safe

Similar to fast-safe-stringify, json-stringify-safe provides a way to safely serialize objects into JSON strings, handling circular references by replacing them with a custom string. It's a bit slower compared to fast-safe-stringify but serves a similar purpose.

flatted

Flatted is a package that serializes and deserializes JavaScript objects, including nested and circular references. Unlike fast-safe-stringify, which returns a JSON string, Flatted returns a flattened string representation that can be re-parsed into the original object structure, including circular references.

README

fast-safe-stringify

Safely and quickly serialize JavaScript objects

Detects circular dependencies instead of throwing (as per usual JSON.stringify usage)

Usage

var safeStringify = require('fast-safe-stringify')
var o = { a: 1 }
o.o = o

console.log(safeStringify(o))  // '{"a":1,"o":"[Circular]"}'
console.log(JSON.stringify(o)) //<-- throws

toJSON support

fast-safe-stringify would not attempt to detect circular dependencies on objects that have a toJSON function. If you need to do that, you will need to attach a toJSON.forceDecirc = true property, like so:

var obj = {
  toJSON: function () {
    // something here..
    return { something: 'else' }
  }
}
obj.toJSON.forceDecirc = true

Benchmarks

The json-stringify-safe module supplies similar functionality with more info and flexibility.

Although not JSON, the core util.inspect method can be used for similar purposes (e.g. logging) and also handles circular references.

Here we compare fast-safe-stringify with these alternatives:

inspectBench*10000: 44.441ms
jsonStringifySafeBench*10000: 38.324ms
fastSafeStringifyBench*10000: 25.165ms

inspectCircBench*10000: 66.541ms
jsonStringifyCircSafeBench*10000: 37.949ms
fastSafeStringifyCircBench*10000: 33.801ms

inspectDeepBench*10000: 377.053ms
jsonStringifySafeDeepBench*10000: 658.650ms
fastSafeStringifyDeepBench*10000: 268.092ms

inspectDeepCircBench*10000: 351.387ms
jsonStringifySafeDeepCircBench*10000: 695.964ms
fastSafeStringifyDeepCircBench*10000: 256.660ms

Protip

Whether you're using fast-safe-stringify or json-stringify-safe if your use case consists of deeply nested objects without circular references the following pattern will give you best results:

var fastSafeStringify = require('fast-safe-stringify')
function tryStringify (obj) {
  try { return JSON.stringify(obj) } catch (_) {}
}
var str = tryStringify(deep) || fastSafeStringify(deep)

If you're likely to be handling mostly shallow or one level nested objects, this same pattern will degrade performance - it's entirely dependant on use case.

JSON.stringify options

JSON.stringify's replacer and space options are not supported. Any value other than 0 for space halves the speed, and providing a replacer function can result in a segfault. Given that the primary focus of this serializer is speed, the trade offs for supporting these options are not desirable.

Acknowledgements

Sponsored by nearForm

License

MIT